docs: document git-ref-based docs versioning by devin-ai-integration[bot] · Pull Request #6558 · fern-api/docs

devin-ai-integration · 2026-08-06T18:07:18Z

Summary

Documents ref: on a docs.yml version entry (fern#17288) as a new section on the existing Versions page, plus a changelog entry.

The section is deliberately opinionated: ref: is framed as the way to serve frozen versions archived at a past release, not versions under active maintenance, because fern docs dev previews working-tree versions only and ref-backed content is built at publish. The recommended shape is a single main/master branch holding current docs and the full versions: list, with past releases archived at tags — the alternative to long-lived version branches.

Also notes that tags/SHAs are immutable while branch refs re-resolve on every publish, and how Fern picks what to build at the ref (the ref's default version if its docs.yml is versioned, otherwise its top-level navigation).

Link to Devin session: https://app.devin.ai/sessions/bd012060ec3549629c8a073910ae761d

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration · 2026-08-06T18:07:20Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

Ryan-Amirthan · 2026-08-06T18:11:21Z


+## Build a version from a git ref
+
+Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, API definitions, and committed library output from it, composed with the current branch's theme, shell, and `versions` metadata.


You can just build that versions content

Trimmed to "builds that version's content from it" in 4fd1354 (same in the changelog entry).

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan · 2026-08-06T18:12:48Z

+
+Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content.
+
+At the ref, Fern builds the navigation from that commit's `versions[0].path`, falling back to its top-level `navigation`. The ref's own `versions` list isn't followed, so older versions declared there are ignored. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build.


does versions[0].path mean anything for an end user?

No — that was internal shorthand. Reworded in 305a279: "If the ref's own docs.yml is versioned, Fern builds its default version (the first entry in its versions list) and ignores the rest; otherwise it builds the ref's top-level navigation."

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan · 2026-08-06T18:40:43Z

+  - display-name: Latest
+    path: ./versions/latest.yml   # built from the working tree
+  - display-name: v2
+    ref: v2.0.0                   # built from the tag v2.0.0


add an example of a branch as well

Added in 67d6c50 — the example now shows a branch (release/v2) alongside the tag (v1.0.0).

Ryan-Amirthan · 2026-08-06T18:40:58Z

+```
+</CodeBlock>
+
+A version entry sets either `path` or `ref`, never both. Declaring both fails `fern check`.


dont think u need to explicitly mention

Dropped in 67d6c50.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan · 2026-08-06T18:41:46Z

+
+Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content.
+
+If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build.


shallow CI checkouts are backfilled with a targeted fetch. If a version's library reference output is missing at the ref, Fern warns and skips that section rather than failing the build.

^ not necessary to add

Removed both in e87a1e3; the paragraph now ends at "Publishing requires git and access to the remote."

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

github-actions · 2026-08-06T19:31:18Z

🌿 Preview your docs: https://fern-preview-devin-1786039614-git-ref-versioning-docs.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

github-actions · 2026-08-06T20:00:43Z

+<CodeBlock title="docs.yml">
+```yaml {5}
+versions:
+  - display-name: Latest


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'Latest' that become outdated

github-actions · 2026-08-06T20:00:43Z

+```yaml {5}
+versions:
+  - display-name: Latest
+    path: ./versions/latest.yml   # built from the working tree


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'latest' that become outdated

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

claude

Claude Code Review

Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.

_{Tip: disable this comment in your organization's Code Review settings.}

docs: document git-ref-based docs versioning

410cdc7

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot requested a review from devalog as a code owner August 6, 2026 18:07

Ryan-Amirthan reviewed Aug 6, 2026

View reviewed changes

Ryan-Amirthan and others added 2 commits August 6, 2026 18:11

docs: simplify git ref build description

4fd1354

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs: use 'frozen versions' instead of 'snapshot versioning'

f5e054e

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan reviewed Aug 6, 2026

View reviewed changes

docs: describe ref content root in user terms

305a279

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan reviewed Aug 6, 2026

View reviewed changes

docs: add branch ref example; drop path/ref exclusivity note

67d6c50

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Ryan-Amirthan reviewed Aug 6, 2026

View reviewed changes

docs: trim shallow-checkout and library-output details

e87a1e3

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

github-actions Bot reviewed Aug 6, 2026

View reviewed changes

docs: replace 'frozen versions' with plain description

6f83a80

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

claude Bot reviewed Aug 6, 2026

View reviewed changes

reorganize content a bit

baf09e2

devalog approved these changes Aug 6, 2026

View reviewed changes

Ryan-Amirthan approved these changes Aug 6, 2026

View reviewed changes

Ryan-Amirthan merged commit 63b7a5e into main Aug 7, 2026

Ryan-Amirthan deleted the devin/1786039614-git-ref-versioning-docs branch August 7, 2026 12:56


		## Build a version from a git ref

		Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, API definitions, and committed library output from it, composed with the current branch's theme, shell, and `versions` metadata.


		Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content.

		At the ref, Fern builds the navigation from that commit's `versions[0].path`, falling back to its top-level `navigation`. The ref's own `versions` list isn't followed, so older versions declared there are ignored. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build.


		Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content.

		If the ref's own `docs.yml` is versioned, Fern builds its default version (the first entry in its `versions` list) and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing requires git and access to the remote; shallow CI checkouts are backfilled with a targeted fetch. If a version's [library reference output](/learn/docs/api-references/library-reference) is missing at the ref, Fern warns and skips that section rather than failing the build.

Uh oh!

Conversation

devin-ai-integration Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

devin-ai-integration Bot commented Aug 6, 2026

🤖 Devin AI Engineer

Uh oh!

Ryan-Amirthan Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Ryan-Amirthan Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Ryan-Amirthan Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Ryan-Amirthan Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Ryan-Amirthan Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 6, 2026

Uh oh!

github-actions Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

devin-ai-integration Bot commented Aug 6, 2026 •

edited

Loading